This is just a half of the changes required for the release - we'll need to:

• do the second part in the secure release repo (polling + actual release)
• create and configure the new package on npm side (with Fabian)
• allowlist the package in both internal npm proxies

I can take care of those items after my OOO 👍

What are the reasons to extract this as a separate package already? Is it only about the size or do you have other concerns?

I totally get the idea of exporting such useful auth-related helpers - but wouldn't it be easier if we did it as a part of the @databricks/lakebase package from the maintenance point of view?

P2 (correctness, reliability) · confidence 100 — getLakebasePgConfig returns buildLakebasePgConfig(...).poolConfig and discards dispose; getLakebaseOrmConfig builds on it and exposes no dispose either. With the new mode: "eager" default, createPasswordProvider starts an unref'd background timer that re-fetches an OAuth credential roughly hourly forever, per call, with no way to stop it — a regression from the old lazy (timer-free) behaviour for the documented TypeORM/Sequelize path. createLakebasePool is unaffected (it wraps pool.end → dispose).

Fix: default these two helpers to refresh: "lazy" (matches old behaviour), or return { ...config, dispose } and document calling it on shutdown.

P3 (maintainability) · confidence 100 — telemetry?/logger? are vestigial: every caller passes only config, yet they're part of the exported getLakebasePgConfig signature. Likewise DriverTelemetry and TokenRefreshDeps (the latter tied to the deprecated createTokenRefreshCallback) are re-exported from packages/lakebase/src/index.ts with no importer outside the package.

Fix: drop the dead params and trim those two exports.

P2 (reliability) · confidence 100 — span.end() only runs on the happy path. When generateDatabaseCredential throws, the catch at L79 rethrows without ending the span (raw OTel startActiveSpan does not auto-end on throw). Every failed refresh leaks an unclosed span.

Fix: try { … span.setStatus({code: OK}) } catch (e) { span.recordException(e); span.setStatus({code: ERROR}); throw e } finally { span.end() }.

P2 (adversarial, reliability) · confidence 100 — withRetries retries on every thrown error. A non-transient failure (403/permission, ConfigurationError, ValidationError) is still retried across the full [50, 500, 5000]ms schedule (~5.5s) before surfacing — and in eager mode this compounds with the 30s background reschedule, so a misconfigured endpoint fires 4 doomed fetches every 30s for the process lifetime. The docs promise transient retries.

Fix: add a shouldRetry?: (err) => boolean predicate (default-true for back-compat) and fast-fail 4xx/config/validation errors.

P2 (api-contract; security: improvement) · confidence 100 — prefer (and require) now fall through to { rejectUnauthorized: true }, and the default changed require → verify-full. Old @databricks/lakebase mapped prefer → { rejectUnauthorized: false }. This is a security improvement, but a silent breaking behaviour change: a deployment relying on prefer/PGSSLMODE=prefer against an unverifiable cert will now fail to connect.

Fix: add a BREAKING CHANGE changelog entry and bump @databricks/lakebase minor (0.3.0 → 0.4.0); a fix:/chore: commit only yields a patch.

P3 (reliability) · confidence 75 — scheduleNext(BACKGROUND_RETRY_MS) reschedules a failed background refresh exactly 30s later with no jitter. Multiple pools/processes started together that hit the same outage all retry at the same instants (T+30s, T+60s…) — a synchronized thundering herd.

Fix: add jitter, e.g. BACKGROUND_RETRY_MS + Math.random() * BACKGROUND_RETRY_MS * 0.5.

P2 (adversarial) · confidence 80 — getToken() does cachedToken = refresh(), overwriting the cache with a possibly-rejecting promise while the previous token is still valid for up to earlyRefreshMs (default 2 min). A transient outage in that pre-expiry window makes lazy mode fail 100% of new connections even though a usable token was in hand (eager mode doesn't have this).

Fix: keep the last successfully-resolved token+expiry separately and serve it until actual expiry; only surface the rejection once no valid token remains.

P2 (maintainability, api-contract) · confidence 100 — parseConfig, ParsedAuthConfig, mapSslConfig, getUsernameSync, withRetries, DEFAULT_RETRY_SCHEDULE are exported from the package entry but imported by no consumer outside this package. Once published they become committed public API (breaking to remove later).

Fix: trim the surface to getPgConfig, createPasswordProvider, generateDatabaseCredential, getUsernameWithApiLookup, errors and types; keep the rest as internal module exports. (Also addresses the knip note in the review summary.)

P2/P3 (api-contract, project-standards) · confidence 75/70 — two issues on this version pin:

• Exact pin + release ordering: lakebase's workspace:* dep on @databricks/lakebase-auth is rewritten to the exact version. The two prepare-release-* workflows are independent and path-triggered, so nothing guarantees lakebase-auth@0.1.0 publishes before the lakebase release that requires it (first publish breaks otherwise); the exact pin also blocks lakebase-auth patch fixes from reaching lakebase consumers without re-releasing lakebase. Fix: emit `^${depPkg.version}` and coordinate lakebase-auth-first on the initial publish.
• Prerelease mismatch: in a prerelease build the lakebase-auth tarball is 0.1.0-pr.<sha> but this still pins plain 0.1.0. It only resolves in the template because prepare-template-artifact.ts adds an overrides entry (matched by name); installing the lakebase prerelease tarball directly would try to resolve 0.1.0 from the registry → stale/missing.

P3 (testing) · confidence 95 — expect(onLog).toHaveBeenCalled() only proves the function ran; it won't catch a wrong level, format string, or args. (Same pattern at pool-config.test.ts:193 with logger.error.) Compare retry.test.ts, which asserts all four args.

Fix: expect(onLog).toHaveBeenCalledWith('warn', expect.stringContaining('retrying'), 30000, expect.stringContaining('boom')).